<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>png++: Main Page</title>

<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css" />



</head>
<body>
<div id="top"><!-- do not remove this div! -->


<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  
  
  <td style="padding-left: 0.5em;">
   <div id="projectname">png++
   &#160;<span id="projectnumber">0.2.1</span>
   </div>
   
  </td>
  
  
  
 </tr>
 </tbody>
</table>
</div>

<!-- Generated by Doxygen 1.7.6.1 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li class="current"><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="namespaces.html"><span>Namespaces</span></a></li>
      <li><a href="annotated.html"><span>Classes</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
    </ul>
  </div>
</div>
<div class="header">
  <div class="headertitle">
<div class="title">png++ Documentation</div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h2><a class="anchor" id="sec_intro"></a>
Introduction</h2>
<p>This is the documentation for png++ the C++ wrapper for libpng. This page documents png++ version 0.2.</p>
<p>PNG++ aims to provide simple yet powerful C++ interface to libpng, the PNG reference implementation library. PNG++ is free software distributed under a modified variant of BSD <a href="http://www.nongnu.org/pngpp/license.html">license</a>.</p>
<h2><a class="anchor" id="sec_news"></a>
News</h2>
<ul>
<li>Added support for tRNS chunk.</li>
<li>Added non-std IO streams support.</li>
<li>Fixed 16-bit endianness problems.</li>
<li>Improved test script.</li>
</ul>
<h2><a class="anchor" id="sec_getting_started"></a>
Getting started</h2>
<p>The following code demonstrates how to read and write PNG images using png++:</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="classpng_1_1image.html" title="Class template to represent PNG image.">png::image&lt; png::rgb_pixel &gt;</a> image(<span class="stringliteral">&quot;input.png&quot;</span>);
 image.write(<span class="stringliteral">&quot;output.png&quot;</span>);
</pre></div><p>The code reads an image from the file named <code>input.png</code>, then writes the image to a file named <code>output.png</code>. The image class template allows you to specify the desired pixel type for the image data. The available pixel types include: RGB, Grayscale and Indexed pixels. Some of the pixel types can have an alpha channel.</p>
<p>The png++ naturally supports reading PNG images of any color type into RGB or Grayscale pixel buffers (with optional alpha channel). This is particularly useful for an image viewer if it needs to display the PNG image on, for example, RGB device regardless of the image color type.</p>
<p>On the other hand one might want to read only images of particular type. With png++ you can specify it this way:</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="classpng_1_1image.html" title="Class template to represent PNG image.">png::image&lt; png::rgb_pixel &gt;</a> image(<span class="stringliteral">&quot;rgb.png&quot;</span>, <a class="code" href="structpng_1_1require__color__space.html" title="IO transformation class template. Enforces image color space.">png::require_color_space&lt; png::rgb_pixel &gt;</a>());
</pre></div><h2><a class="anchor" id="sec_installing"></a>
Installing</h2>
<p>PNG++ comes as a set of header files and does not require compilation to be installed. For the same reason there are no binary packages for png++.</p>
<h3><a class="anchor" id="subs_prerequisites"></a>
Prerequisites</h3>
<ul>
<li>png++ works with libpng-1.2.x.</li>
<li>png++ compiles with g++-4.1 and g++-4.2. Other version should work well too.</li>
<li>png++ relies on GNU make for compiling tests and examples; in particular it uses "remaking makefiles" feature</li>
<li>Documentation is produced using <a href="http://www.doxygen.org/">doxygen</a>. See the bottom of this page for doxygen version used to compile these docs.</li>
</ul>
<h3><a class="anchor" id="subs_installing_pngpp"></a>
Installing png++</h3>
<p>Follow these instructions in order to install png++:</p>
<ol type="1">
<li>Unpack source package: <div class="fragment"><pre class="fragment">$ tar -zxf png++-0.2.x.tar.gz -C ~/src </pre></div></li>
<li>Go to your brand new png++ sources directory: <div class="fragment"><pre class="fragment">$ cd ~/src/png++-0.2.x </pre></div></li>
<li>Issue <code>make</code> to test how it's doing: <div class="fragment"><pre class="fragment">$ make </pre></div> This will compile examples in the <code>example</code> directory. If everything goes well, try <div class="fragment"><pre class="fragment">$ make test </pre></div> (or <code>make</code> <code>check</code> which is the same as above) to run the test suite. If tests do not produce error messages then probably all is OK.</li>
<li>Now you can create documentation (optional). Use <div class="fragment"><pre class="fragment">$ make docs </pre></div> to run <code>doxygen</code> in the sources directory.</li>
<li>Now it is time to become <code>root</code> and install png++ into your system. It's OK to issue <code>make</code> <code>install</code> under ordinary user permissions if you want to install png++ into your home directory. Run the following command: <div class="fragment"><pre class="fragment">$ make install PREFIX=$HOME </pre></div> to copy png++ header files to <code>~/include/png++</code> and documentation files to <code>~/share/doc/png++-0.2.x</code>. Without a <code>PREFIX</code> png++ installs to <code>/usr/local</code>.</li>
</ol>
<h2><a class="anchor" id="sec_working_with_images"></a>
Working with images</h2>
<p>In png++ you can create new images like this:</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor"> #include &lt;png++/png.hpp&gt;</span>
 <span class="comment">//...</span>
 <a class="code" href="classpng_1_1image.html" title="Class template to represent PNG image.">png::image&lt; png::rgb_pixel &gt;</a> image(128, 128);
 <span class="keywordflow">for</span> (<span class="keywordtype">size_t</span> y = 0; y &lt; image.get_height(); ++y)
 {
     <span class="keywordflow">for</span> (<span class="keywordtype">size_t</span> x = 0; x &lt; image.get_width(); ++x)
     {
         image[y][x] = <a class="code" href="namespacepng.html#ace408e0073475efdd27ce3421ce9bbd0">png::rgb_pixel</a>(x, y, x + y);
         <span class="comment">// non-checking equivalent of image.set_pixel(x, y, ...);</span>
     }
 }
 image.write(<span class="stringliteral">&quot;rgb.png&quot;</span>);
</pre></div><p>Optionally, you may specify </p>
<div class="fragment"><pre class="fragment"> image.set_interlace_type(<a class="code" href="namespacepng.html#a4b468278362e4ccf0b2c52f9c0692bdcae24fce8bcef2f096696944120351c9d2">png::interlace_adam7</a>)
</pre></div><p> to produce an interlaced image.</p>
<p>If you are writing an indexed colors image, you should provide a palette (colormap). One of the ways to do this is the following:</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor"> #include &lt;png++/png.hpp&gt;</span>
 <span class="comment">//...</span>
 <a class="code" href="classpng_1_1image.html" title="Class template to represent PNG image.">png::image&lt; png::index_pixel &gt;</a> image;
 <a class="code" href="namespacepng.html#a6c5f0b8146f3467ea94e6090846d1d01" title="The palette type. Currently implemented as std::vector of png::color.">png::palette</a> pal(256);
 <span class="keywordflow">for</span> (<span class="keywordtype">size_t</span> i = 0; i &lt; pal.size(); ++i)
 {
     pal[i] = <a class="code" href="structpng_1_1color.html" title="PNG color struct extension. Adds constructors.">png::color</a>(i, 255 - i, i);
 }
 image.<a class="code" href="classpng_1_1image.html#ab1fb2c3e15ac8d90d8436636f9a40da3" title="Replaces the image palette.">set_palette</a>(pal);
 ...
 image.<a class="code" href="classpng_1_1image.html#afd2cc57ec02efce3103573fba054a4aa" title="Writes an image to specified file.">write</a>(<span class="stringliteral">&quot;palette.png&quot;</span>);
</pre></div><p>It is not absolutely necessary to have the whole image data in memory in order to write a PNG file. You can use generator class template to write the image row-by-row. An example of this is provided in <code>example/pixel_generator.cpp</code> bundled with the sources package.</p>
<p>The same holds for reading images too. You can use consumer class template in order to read the image data row-by-row. This might help in applications which have to deal with large PNG images but do not want to read the entire image into memory.</p>
<p>You can read or write images from/to generic IO stream, not only file on disk. Check out <code>image::read(std::istream&amp;)</code>, <code>image::write(std::ostream&amp;)</code> overloads in the reference manual.</p>
<h2><a class="anchor" id="sec_compiling_user"></a>
Compiling your programs</h2>
<p>Use the following command to compile your program:</p>
<div class="fragment"><pre class="fragment">$ g++ -c example.cpp `libpng-config --cflags` </pre></div><p>and the following to link it:</p>
<div class="fragment"><pre class="fragment">$ g++ -o example example.o `libpng-config --ldflags` </pre></div><p>When compiling you should add <code>-I</code> <code>$PREFIX/include</code> if you have installed png++ to non-standard location, like your home directory.</p>
<p>In your program, the line</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor"> #include &lt;png++/png.hpp&gt;</span>
</pre></div><p>brings in all the header files in png++ which should be suitable for the most of the applications. You may include only the headers you really use, for example:</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor"> #include &lt;png++/image.hpp&gt;</span>
<span class="preprocessor"> #include &lt;png++/rgb_pixel.hpp&gt;</span>
</pre></div><p>If do not want to install png++ headers you still can compile your programs. Just create a subdirectory named <code>png++</code> somewhere in your project tree and copy all of the <code></code>.hpp files in png++ distribution there. Then use appropriate compiler options to add this directory into the header search path.</p>
<h2><a class="anchor" id="sec_further"></a>
Further reading</h2>
<ul>
<li>To get information about specific features, use reference (can be reached from the top of this page).</li>
<li>If you are looking for more example code, please go to the <code>example/</code> directory of the source distribution. You may also find sources in the <code>test/</code> directory insightful (well, somewhat).</li>
<li>Have a question? Check out <a class="el" href="index.html#sec_help">Getting help</a> section below.</li>
<li>Of course, your ultimate source for learning is the source code. <code>:-)</code></li>
</ul>
<h2><a class="anchor" id="sec_download"></a>
Download</h2>
<p>The project is hosted at Savannah: <a href="http://savannah.nongnu.org/projects/pngpp/">http://savannah.nongnu.org/projects/pngpp/</a></p>
<p>Released source packages can be found here: <a href="http://download.savannah.nongnu.org/releases/pngpp/">http://download.savannah.nongnu.org/releases/pngpp/</a></p>
<p>Also, you can check out sources directly from SVN repository: svn://svn.sv.nongnu.org/pngpp/trunk/ or <a href="http://svn.sv.nongnu.org/pngpp/trunk/">http://svn.sv.nongnu.org/pngpp/trunk/</a> (for people w/o outgoing svn).</p>
<p>Online version of this documentation can be found here: <a href="http://www.nongnu.org/pngpp/doc/0.2.3/index.html">http://www.nongnu.org/pngpp/doc/0.2.3/index.html</a></p>
<h2><a class="anchor" id="sec_bugs"></a>
Bugs</h2>
<p>The following is a list of known bugs and limitations:</p>
<ul>
<li>Lacks support for output transformations</li>
<li>Lacks support for optional/unknown chunks in PNG data stream</li>
<li>Documentation sucks <code>;-)</code></li>
</ul>
<p>To report bugs, please use Savannah bug tracker: <a href="http://savannah.nongnu.org/bugs/?group=pngpp&func=additem">http://savannah.nongnu.org/bugs/?group=pngpp&amp;func=additem</a></p>
<p>Do not forget to check if the bug was already filed. <code>:-)</code></p>
<h2><a class="anchor" id="sec_help"></a>
Getting help</h2>
<p>There is a mailing list for developers: <a href="http://lists.nongnu.org/mailman/listinfo/pngpp-devel">http://lists.nongnu.org/mailman/listinfo/pngpp-devel</a></p>
<p>You can also contact me by dropping a mail to &lt;<a href="mailto:alex.shulgin@gmail.com">alex.shulgin@gmail.com</a>&gt;.</p>
<p>Happy hacking!</p>
<p>Alex Shulgin </p>
</div></div><!-- contents -->


<hr class="footer"/><address class="footer"><small>
Generated on Fri Jan 25 2013 14:10:10 for png++ by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.7.6.1
</small></address>

</body>
</html>
